Skip to content

feat: add experimental acpx flows runtime and examples#179

Merged
osolmaz merged 22 commits intomainfrom
codex/acpx-flows-doc-plan
Mar 26, 2026
Merged

feat: add experimental acpx flows runtime and examples#179
osolmaz merged 22 commits intomainfrom
codex/acpx-flows-doc-plan

Conversation

@osolmaz
Copy link
Contributor

@osolmaz osolmaz commented Mar 25, 2026

Summary

  • add an experimental acpx/flows runtime and flow run <file> for TypeScript workflow modules
  • add generic flow primitives for ACP steps, local computation, checkpoints, and runtime-owned actions
  • add per-step cwd, live run state, timeouts, JSON helpers, and file-backed flow persistence under ~/.acpx/flows/runs
  • add shipped flow examples under examples/flows/, including a larger PR-triage example with a colocated written workflow description
  • refactor the flow, queue, and CLI internals so the new surface stays maintainable
  • document the flow model consistently across the README, CLI docs, architecture doc, examples, and skills/acpx/SKILL.md

Notes

  • the core flow surface stays generic; workload-specific behavior is shown as an example flow rather than being baked into the CLI
  • example workflows can perform real side effects if run against live repositories

Validation

  • pnpm run check
  • pnpm run check:docs
  • source and built smoke runs against the shipped flow examples during development

Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0674e7d1a2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@osolmaz osolmaz changed the title docs: add acpx flows implementation plan feat: add experimental flow runner Mar 25, 2026
@osolmaz osolmaz changed the title feat: add experimental flow runner feat: add experimental acpx flows runtime Mar 26, 2026
@osolmaz osolmaz changed the title feat: add experimental acpx flows runtime feat: add experimental acpx flows runtime and examples Mar 26, 2026
@osolmaz
Copy link
Contributor Author

osolmaz commented Mar 26, 2026

Final report on current head 8bc3af0:

  • Implemented routable flow node outcomes with separate result tracking, plus timeout-aware flow execution and persistence.
  • Hardened flow runtime behavior after review: shell/action cwd handling, end-to-end timeout coverage across node phases, unique live-state temp writes, signal-aware shell failures, external acpx/flows import support for authored flow files, and queue-owner arg sanitization for debugger flags.
  • Added/updated regression coverage for timeout routing, async callback/parse timeout cases, concurrent live writes, signal exits, external flow imports, and debugger-flag sanitization.
  • Resolved the stale Codex review thread and verified the remaining docs/examples are in sync.

Validation run on this head:

  • pnpm run check
  • pnpm run check:docs ✅ (earlier in the branch; docs-only updates remained covered)
  • codex review --base main -> addressed surfaced P1 items around flow cwd/timeout handling and external flow import resolution; no remaining unresolved P0/P1 feedback on the branch
  • Built CLI smoke for external flow imports ✅
    • node dist/cli.js --approve-all --cwd <tmpdir> --format json flow run <tmp-flow.ts>

What I could not fully verify locally:

  • I did not exercise a real third-party external project with its own helper modules beyond the temp external-flow smoke.
  • I did not do staging/production verification beyond GitHub Actions CI on this PR.

CI is green on the current PR head.

@osolmaz osolmaz self-assigned this Mar 26, 2026
@osolmaz osolmaz merged commit 697ee1f into main Mar 26, 2026
8 checks passed
@osolmaz osolmaz deleted the codex/acpx-flows-doc-plan branch March 26, 2026 16:11
@osolmaz
Copy link
Contributor Author

osolmaz commented Mar 26, 2026

Landed via temp rebase onto main.

  • Gate: validation completed for this repo's change scope
  • Land commit: 7e154e9
  • Merge commit: 697ee1f

Thanks @osolmaz!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant